home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 351-375 / disk_352 / mg / docs / mgprog.doc < prev    next >
Text File  |  1992-05-06  |  11KB  |  296 lines

  1. This documentation covers mg 2a.
  2.  
  3. I do want feedback from other mg developers on what they think of my
  4. changes, documentation, and what needs to be done to make mg better.
  5. This document is not complete, it mainly covers the areas I have
  6. recently changed.
  7.  
  8. Possible future changes:
  9.  
  10. Rearange file contents along more rational lines.  Further split the
  11. monolithic def.h file.
  12.  
  13. Changing the echo line stuff to use a minibuffer keymap.
  14.  
  15. Making the kill buffer a linked list of lines.
  16.  
  17. Variables.
  18.  
  19. Allow for backspace, ^s, etc. to be changed in some reasonable manner.
  20. (Probably using variables or a simulation thereof.)  I do not think an
  21. input keymap is the correct solution, even if it is frequently used in
  22. Gnu emacs.  (Besides the extra overhead, keynames come out wrong.)
  23.  
  24. Make long lines wrap like they do in GNU emacs.
  25.  
  26. Fix known (and unknown :-) bugs.
  27.  
  28. Have the keymaps and associated tables generated by a program.
  29.  
  30.  
  31. Known bugs/limitations:
  32.  
  33. Binding a key in a named keymap may or may not change the binding of
  34. other keys pointing to the same keymap.     (i.e. if ^H and ^_ are bound
  35. to help, rebinding ^Hb may not (or may) change ^_b.  This can be cured
  36. by rebinding ^_ to help.)
  37.  
  38. Overwrite mode does not work in macros.     (Characters are inserted
  39. rather than overwriting.)
  40.  
  41. Dired mode has some problems:  Rename does not update the buffer.
  42. Doing a dired again will update the buffer (whether it needs it or
  43. not) and will lose any marks for deletion.  .. and . are not
  44. recognized as special cases.
  45.  
  46.  
  47.  
  48. New implementation oddities:
  49.  
  50. insert and define-key are new commands corresponding to the mocklisp
  51. functions in Gnu Emacs.     (Mg does not have non-command functions.)
  52. (Mg's insert will only insert one string.)
  53.  
  54. The display wrap code does not work at all like that of GNU emacs.
  55.  
  56.  
  57.  
  58. Adding command functions to mg:
  59.  
  60. Command functions take two integer aguments and return an integer.
  61. The first argument, f, is a set of flags.  (f&FFARG) is non-zero if a
  62. numeric arguement was passed to the function.  (There are bits
  63. indicating how the agument was specified, but they are not fully
  64. impleminted.)  (f&FFRAND) is non-zero if the function is being called
  65. by another function and that possibly slightly different action should
  66. be taken.  (No error checking, supress output, etc.)  The second
  67. argument, n, is the numeric agument passed or one if there was no
  68. numeric arugment.  The fuction should return TRUE if it executes
  69. correctly, FALSE if it could not, and ABORT if the user typed the
  70. keyboard quit character at a prompt.
  71.  
  72. The function must be added to the functnames table in keymap.c.     This
  73. table must be kept in assending ascii sequence.
  74.  
  75.  
  76.  
  77. Key maps:
  78.  
  79. Key maps are structures containing information on what action should
  80. be taken corresponding to an individual keypress.  That action could
  81. be an indication that this is a prefix key and the next kepress should
  82. be looked up in another keymap.
  83.  
  84.     Example keymap:
  85.  
  86.     static    struct    KEYMAPE(6+IMAPEXT)    cXmap = {
  87.         6,
  88.         6+IMAPEXT,
  89.         rescan,
  90.         {
  91.             {CCHR('B'),CCHR('G'),    cXcB,    (KEYMAP *)NULL},
  92.             {CCHR('L'),CCHR('X'),    cXcL,    (KEYMAP *)NULL},
  93.             {'(',    ')',        cXlp,    (KEYMAP *)NULL},
  94.             {'0',    '4',        cX0,    (KEYMAP *)&cX4map},
  95.             {'=',    '=',        cXeq,    (KEYMAP *)NULL},
  96.             {'^',    's',        cXcar,    (KEYMAP *)NULL},
  97.         }
  98.     };
  99.  
  100. (Note: this example is a simplified example of a real keymap in keymap.c.)
  101.  
  102. Since C does not directly support structures containing undementioned
  103. arrays, the macro KEYMAPE is used to create a structure with an array
  104. of the proper size.  6 is the current size of the array, and IMAPEXT
  105. is the number of extra elements left for future groth (by rebinding
  106. keys) before the map must be reallocated.  rescan is the function to
  107. be executed if a specific entry for the key is not found.  (rescan is
  108. a special function that searches for something else to do -- first by
  109. trying lowercasing the last character in the keymap, then by trying
  110. the other modes in effect.)
  111.  
  112. The array elements must be in order by the keys they define.  Each
  113. covers a range of characters.  Numeric values should not be used for
  114. characters, they make porting mg to some other systems harder.    The
  115. CCHR macro may be used to specify control characters, including DEL
  116. (CCHR('?')).  cXcB, cXcL, etc. are arrays of pointers to functions
  117. returning int.    One of these fuction pointers per element may be to
  118. the pseuto-function prefix.  cX4map is the keymap coresponding to the
  119. prefix function bound to '4' in this keymap.  Having several keys in
  120. an element bound to the default function is better than increasing the
  121. number of elements.
  122.  
  123.  
  124.  
  125. Modes:
  126.  
  127. Modes are named key maps that are scanned for key bindings before the
  128. global keymap is.  There are functions in modes.c to toggle modes on
  129. or off for individual buffers.  Note that the "major"/"minor" mode
  130. distiction is different than in Gnu Emacs.  Dired is currently the
  131. only major mode available, buffers are put into dired mode on creation
  132. by the dired code.  (The distiction in mg is the major mode replaces
  133. the default keymap instead of being an overlay.) Some modes (overwrite
  134. and no-tab) also trigger per-buffer flags that should be convered to
  135. per-buffer variables when we add variables.  Keymaps for the modes are
  136. kept in keymap.c with the other keymaps.
  137.  
  138.  
  139.  
  140. System dependent files:
  141.  
  142. Fileio.c:
  143.     Contains file i/o routines:
  144.         ffputbuf(BUFFER *):
  145. Write all lines of buffer to the file.    The last line of the buffer does
  146. NOT have the normally implied newline.    (One may be added if
  147. nessisary, but don't write out the last line if it is zero characters
  148. long.)
  149.  
  150.         ffgetline(char *buf, int nbuf, int *nbytes):
  151. Read a line from the file up to the length specified by the second
  152. argument in to the buffer pointed to by the first.  If a newline is
  153. not found after reading nbuf characters, return FIOLONG and on the
  154. next call to ffgetline return the remaining portion (or nbuf more
  155. characters and return FIOLONG).     If a newline is found, set *nbytes to
  156. the number of characters read and return FIOSUC.  If the end of file
  157. is descovered, set *nbytes and return FIOEOF.  (If the file ends in a
  158. newline, the call returning FIOEOF will set *nbytes to 0.)  If any
  159. other error occurs, return FIOERR.
  160.  
  161.         char *adjustname(char *fname)
  162. Standardize filename.  On mono-case systems, lowercase the file name.
  163. If NO_DIR is not defined, make fully qualified.     (not relitive to the
  164. current directory, which may change.)
  165.  
  166.         fncmp(char *fna, char *fnb) 
  167. Return 0 if both arguments refer to the same file or buffer.  #define
  168. it to be strcmp on mono-case or case sensitive systems, use a non-case
  169. sensitive compareison otherwise.  (Borrow it from the osk fileio.c)
  170. Both arguments have been through adjustname already. 
  171.  
  172.     routines needed for dired:
  173.  
  174.         rename(char *fromname, char *toname)
  175. rename file.  BSD systems have this as a system call.  return -1 on
  176. error.
  177.  
  178.         copy(char *fromname, char *toname)
  179. copy file.  return -1 on error.
  180.  
  181.         unlinkdir(char *name)
  182. Delete directory.  return -1 on error.  (possibly including non-empty
  183. directory.)
  184.  
  185.         BUFFER *dired_(char *name)
  186. Create dired buffer for named directory.  See example from osk or bsd.
  187.  
  188.         d_makename(LINE *l, char *fname)
  189. Concatinate directory name associated with the current dired BUFFER
  190. with file name in line.  Return ABORT if no file name on line, FALSE
  191. if it is an ordinary file, or TRUE if there is a directory.  Name made
  192. should be the same as if it were run through adjustname. 
  193.  
  194.  
  195. Converting system & terminal dependent files from mg1b:
  196.  
  197. All command functions will have to be rewritten to use the new two
  198. argument calling sequence.  (Some compilers will let you get away
  199. without doing this for testing purposes.  Problems, if any, will show
  200. up at run-time.)
  201.  
  202. Key binding is completly different.  See extend.c if your code needs
  203. to do rebinding.
  204.  
  205. I have attempted make mg less dependant on ascii character values.
  206. Keymap.c depends on ascii sorting order.  Cinfo.c depends on character
  207. values and contains a function to convert from a character value
  208. to a key name.  Several modules assume 3 octal digits are enough for
  209. any character value.
  210.  
  211. Names of most compile time options have changed.  Whatever is most
  212. GNU-emacs like is now the default.
  213.  
  214. sysdef.h:
  215.     The type KEY should not be defined.  The type KCHAR should be defined.
  216.     All posible key inputs must be positive in type KCHAR.    short is
  217.     recomended.
  218.  
  219. spawn.c:
  220.     Update to the new function calling conventions.
  221.  
  222. Makefile:
  223.     Needs complete rewrite.     You can probably figure out the dependencies
  224.     from the bsd or osk one.  Compile time options have changed.
  225.  
  226. Fileio.c:
  227.     Remove function ffputline.  Add function ffputbuf (described above).
  228.     Rewrite ffgetline to conform to the new way of doing things.  (see
  229.     above.)  These routines can probably be borrowed intact from the
  230.     OSK system dependant fileio.c for unix systems.
  231.     Replace adjustcase with adjustname.  Add fncmp either here or
  232.     as a #define in sysdef.h.  Add functions needed by dired.
  233.  
  234.  
  235.  
  236.  
  237. Compile time options:
  238.  
  239. extentions not directly in gnu emacs
  240.  
  241. BSMAP        input mapping exchanging ^H and DEL.
  242.         1 for defaulting to this, 0 for normal default.
  243. NOTAB        for systems that don't like tabs
  244. CVMVAS        arguments to ^V in screens not lines
  245. PREFIXREGION    prefix region
  246. PREVWIND    previous window
  247. GOSREC        Gossling style recenter
  248. STARTUPFILE    (unix & OSK) system-wide startup file
  249. XKEYS        (Termcap) Put kepad in alternate mode, use
  250.         terminal-dependent startup file.
  251.  
  252. Features removeable to save space
  253.  
  254. NO_HELP        help, descibe-bindings, describe-key-briefly, apropos
  255. NO_MACRO    keyboard macros.  If defined, NO_STARTUP must be also.
  256. NO_STARTUP    startup files, load, etc.
  257. NO_BACKUP    backup files when writing
  258. NO_DPROMPT    Delayed prompt on multi-key sequences
  259. NO_DIR        Dir change functions.  If defined, NO_DIRED must be also.
  260. NO_DIRED    Dired mode
  261. REGEX        Regular expressions.  Not default, since the code is rather
  262.         unportable and has the GNU copywrite on it.
  263.  
  264. System dependant garbage (avoid where practical)
  265.  
  266. VMS        VMS
  267. AMIGA        AMIGA
  268.  
  269.  
  270. Things that may be defined in system dependant code:
  271.  
  272. XCHAR        XCHAR and XSHORT    (char and short for space savings)
  273. BDC2        more special characters for filenames
  274. BDC3        dito.
  275. METABIT        Bit of KCHAR set on meta keys
  276. OFFSET        macro to calculate offset of member from start of structure
  277. NBLOCK        line growth amount
  278. KBLOCK        kill buffer growth amount
  279. MALLOCROUND    macro to predict malloc allocations stratagy
  280. SYSINIT        system dependant initialization
  281. NO_VOID_TYPE    compiler dosen't have type void
  282. ZEROARRAY    zero length arrays are allowed
  283. BINDKEY        include bindkey routine for use by system & terminal
  284.         dependent code.
  285.  
  286. Terminal dependant
  287.  
  288. DO_METAKEY    meta key
  289. METABIT        Which bit in a KCHAR is used by the meta key (default 0x80)
  290. STANDOUT_GLITCH standout (may) take character position(s)
  291. GOSLING        optimize redisplay
  292. MEMMAP        memory mapped display
  293. MOVE_STANDOUT    cursor addressing may be done in standout mode
  294. FKEYS        function keys do not fit in type char.
  295.         Not for use where function keys send multiple characters.
  296.